home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 4 / Apprentice-Release4.iso / Languages / MPW Oberon 2.1168 / OInterfaces / Translation.mod < prev    next >
Encoding:
Text File  |  1995-08-10  |  11.8 KB  |  281 lines  |  [TEXT/MPS ]
  1. (*
  2.      File:        Translation.mod
  3.  
  4.      Contains:    Translation Manager (Macintosh Easy Open) Interfaces.
  5.  
  6.      Version:    Technology:    Macintosh Easy Open 1.1
  7.                  Package:    Universal Interfaces 2.0 in “MPW Latest” on ETO #17
  8.  
  9.      Copyright:    © 1984-1995 by Apple Computer, Inc.
  10.                  All rights reserved.
  11.  
  12.      Bugs?:        If you find a problem with this file, use the Apple Bug Reporter
  13.                  stack.  Include the file and version information (from above)
  14.                  in the problem description and send to:
  15.                      Internet:    apple.bugs.applelink.apple.com
  16.                      AppleLink:    APPLE.BUGS
  17.  
  18. *)
  19.  
  20. (*$TAGS-*)
  21. (*$CALLING PASCAL*)
  22. MODULE Translation;
  23.  
  24. IMPORT SYSTEM, Types, Files, TranslationExtensions;
  25.  
  26. (* $PUSH*)
  27. (* $ALIGN MAC68K*)
  28. (* $LibExport+*)
  29.     
  30. TYPE
  31.     DocOpenMethod* = INTEGER;
  32.  
  33.  
  34. CONST
  35.     domCannot*                    = 0;
  36.     domNative*                    = 1;
  37.     domTranslateFirst*            = 2;
  38.     domWildcard*                    = 3;
  39.  
  40. (* 0L terminated array of OSTypes, or FileTypes*)
  41.     
  42. TYPE
  43.     TypesBlock* = ARRAY 64 (*ΔΔ[0..63]ΔΔ*) OF Types.OSType;
  44.  
  45.     TypesBlockPtr* = POINTER TO TypesBlock (*ΔΔ Types.OSType*);
  46.  
  47. (* Progress dialog resource AIFF.ID*)
  48.  
  49. CONST
  50.     kTranslationScrapProgressDialogID* = -16555;
  51.  
  52. (* block of data that describes how to translate*)
  53.  
  54. TYPE
  55.     FileTranslationSpec* = RECORD
  56.         componentSignature*:        Types.OSType;
  57.         translationSystemInfo*:    Types.Ptr;
  58.         src*:                    TranslationExtensions.FileTypeSpec;
  59.         dst*:                    TranslationExtensions.FileTypeSpec;
  60.     END;
  61.  
  62.     FileTranslationSpecArrayPtr* = POINTER TO FileTranslationSpec;
  63.  
  64. (*****************************************************************************************
  65. * 
  66. *   GetFileTypesThatAppCanNativelyOpen
  67. * 
  68. *  This routine returns a list of all FileTypes that an application can open by itself
  69. * 
  70. *  Enter:    appVRefNumHint        volume where application resides (can be wrong, and if is, will be used as a starting point)
  71. *             appSignature        signature (creator) of application
  72. *             nativeTypes            pointer to a buffer to be filled with up to 64 FileTypes
  73. * 
  74. *  Exit:    nativeTypes            zero terminated array of FileTypes that can be opened by app
  75. *)
  76.  
  77. PROCEDURE GetFileTypesThatAppCanNativelyOpen*(appVRefNumHint: INTEGER; appSignature: Types.OSType; VAR nativeTypes: TranslationExtensions.FileType): Types.OSErr;
  78.     (*$IF NOT GENERATINGCFM*)
  79.     INLINE PASCAL $701C, $ABFC;
  80.     (*$END*)
  81. (*****************************************************************************************
  82. * 
  83. *  ExtendFileTypeList
  84. * 
  85. *  This routine makes a new list of file types that can be translated into a type in the given list
  86. *  Used by StandardFile
  87. * 
  88. *  Enter:    originalTypeList        pointer to list of file types that can be opened
  89. *             numberOriginalTypes        number of file types in orgTypeList
  90. *              extendedTypeList        pointer to a buffer to be filled with file types
  91. *             numberExtendedTypes        max number of file types that can be put in extendedTypeList
  92. * 
  93. *  Exit:    extendedTypeList        buffer filled in with file types that can be translated
  94. *             numberExtendedTypes        number of file types put in extendedTypeList
  95. *)
  96. PROCEDURE ExtendFileTypeList*((*CONST*)VAR originalTypeList: TranslationExtensions.FileType; numberOriginalTypes: INTEGER; VAR extendedTypeList: TranslationExtensions.FileType; VAR numberExtendedTypes: INTEGER): Types.OSErr;
  97.     (*$IF NOT GENERATINGCFM*)
  98.     INLINE PASCAL $7009, $ABFC;
  99.     (*$END*)
  100. (*****************************************************************************************
  101. * 
  102. * 
  103. *  This routine checks if a file can be opened by a particular application.
  104. *  If so, it returns if it needs to be translated first, and if so then how.
  105. *  The FileTypes that the app can open are specified by nativelyOpenableTypes,
  106. *  or if it is NULL, GetFileTypesThatAppCanNativelyOpen is called.
  107. * 
  108. *  Enter:    targetDocument        document to check if it can be opened
  109. *             appVRefNumHint        vRefNum of application to open doc ( can be wrong, and if is, will be used as a starting point)
  110. *             appSignature        signature (creator) of application to open doc
  111. *             nativeTypes            zero terminated list of FileTypes app can open natively, or NULL to use default list
  112. *             onlyNative            whether to consider if document can be translated before opening
  113. *             howToOpen            pointer to buffer in which to put how the document can be opened
  114. *             howToTranslate        pointer to buffer in which to put a FileTranslationSpec record
  115. * 
  116. *  Exit:    howToOpen            whether file needs to be translated to be read
  117. *             howToTranslate        if file can be translated, buffer filled in with how to translate
  118. *             returns                noErr, noPrefAppErr
  119. *)
  120. PROCEDURE CanDocBeOpened*((*CONST*)VAR targetDocument: Files.FSSpec; appVRefNumHint: INTEGER; appSignature: Types.OSType; (*CONST*)VAR nativeTypes: TranslationExtensions.FileType; onlyNative: BOOLEAN; VAR howToOpen: DocOpenMethod; VAR howToTranslate: FileTranslationSpec): Types.OSErr;
  121.     (*$IF NOT GENERATINGCFM*)
  122.     INLINE PASCAL $701E, $ABFC;
  123.     (*$END*)
  124. (*****************************************************************************************
  125. * 
  126. *  GetFileTranslationPaths
  127. * 
  128. *  This routine returns a list of all ways a translation can occure to or from a FileType.
  129. *  The app is checked to exist.  The hint for each app is the VRefNum and DTRefNum
  130. * 
  131. *  Enter:    srcDoc            source file or NULL for all matches
  132. *             dstDoc            destination FileType or NULL for all matches
  133. *             maxResultCount
  134. *             resultBuffer
  135. *  Exit:    number of paths
  136. *)
  137. PROCEDURE GetFileTranslationPaths*(VAR srcDocument: Files.FSSpec; dstDocType: TranslationExtensions.FileType; maxResultCount: INTEGER; resultBuffer: FileTranslationSpecArrayPtr): INTEGER;
  138.     (*$IF NOT GENERATINGCFM*)
  139.     INLINE PASCAL $7038, $ABFC;
  140.     (*$END*)
  141. (*****************************************************************************************
  142. * 
  143. *  GetPathFromTranslationDialog
  144. * 
  145. *  This routine, with a given document, application, and a passed typelist will display the
  146. *  Macintosh Easy Open translation dialog allowing the user to make a choice.  The choice
  147. *  made will be written as a preference (so the next call to CanDocBeOpened() will work).
  148. *  The routine returns the translation path information.
  149. * 
  150. *  Enter:    theDocument            Files.FSSpec to document to open
  151. *             theApplication        Files.FSSpec to application to open document
  152. *             typeList            Nil terminated list of FileType's (e.g. StandardFile.SFTypeList-like) of types
  153. *                                 you would like the documented translated to.  Order most perferred
  154. *                                 to least.
  155. * 
  156. *  Exit:    howToOpen            Translation method needed to open document
  157. *             howToTranslate        Translation specification
  158. *             returns                Any errors that might occur.
  159. *)
  160. PROCEDURE GetPathFromTranslationDialog*((*CONST*)VAR theDocument: Files.FSSpec; (*CONST*)VAR theApplication: Files.FSSpec; typeList: TypesBlockPtr; VAR howToOpen: DocOpenMethod; VAR howToTranslate: FileTranslationSpec): Types.OSErr;
  161.     (*$IF NOT GENERATINGCFM*)
  162.     INLINE PASCAL $7037, $ABFC;
  163.     (*$END*)
  164. (*****************************************************************************************
  165. * 
  166. *   TranslateFile
  167. * 
  168. *  This routine reads a file of one format and writes it to another file in another format. 
  169. *  The information on how to translated is generated by the routine CanDocBeOpened.
  170. *  TranslateFile calls through to the TranslateFile Extension's DoTranslateFile routine.  
  171. *  The destination file must not exist.  It is created by this routine.  
  172. * 
  173. *  Enter:    sourceDocument            input file to translate
  174. *             destinationDocument        output file of translation
  175. *             howToTranslate            pointer to info on how to translate
  176. *  Exit:    returns                    noErr, badTranslationSpecErr 
  177. *)
  178. PROCEDURE TranslateFile*((*CONST*)VAR sourceDocument: Files.FSSpec; (*CONST*)VAR destinationDocument: Files.FSSpec; (*CONST*)VAR howToTranslate: FileTranslationSpec): Types.OSErr;
  179.     (*$IF NOT GENERATINGCFM*)
  180.     INLINE PASCAL $700C, $ABFC;
  181.     (*$END*)
  182. (*****************************************************************************************
  183. * 
  184. *   GetDocumentKindString
  185. * 
  186. *  This routine returns the string the Finder should show for the "kind" of a document
  187. *  in the GetInfo window and in the kind column of a list view.  
  188. * 
  189. *  Enter:    docVRefNum        The volume containing the document
  190. *             docType            The catInfo.fdType of the document
  191. *             docCreator        The catInfo.fdCreator of the document
  192. *             kindString        pointer to where to return the string
  193. * 
  194. *  Exit:    kindString        pascal string.  Ex: "\pSurfCalc spreadsheet"
  195. *             returns            noErr, or afpItemNoFound if kind could not be determined
  196. *)
  197. PROCEDURE GetDocumentKindString*(docVRefNum: INTEGER; docType: Types.OSType; docCreator: Types.OSType; VAR kindString: Types.Str63): Types.OSErr;
  198.     (*$IF NOT GENERATINGCFM*)
  199.     INLINE PASCAL $7016, $ABFC;
  200.     (*$END*)
  201. (*****************************************************************************************
  202. * 
  203. *  GetTranslationExtensionName
  204. * 
  205. *  This routine returns the translation system name from a specified TranslationSpec
  206. * 
  207. *  Enter:    translationMethod    The translation path to get the translation name from
  208. * 
  209. *  Exit:    extensionName        The name of the translation system
  210. *             returns                Any errors that might occur
  211. *)
  212. PROCEDURE GetTranslationExtensionName*((*CONST*)VAR translationMethod: FileTranslationSpec; VAR extensionName: Types.Str31): Types.OSErr;
  213.     (*$IF NOT GENERATINGCFM*)
  214.     INLINE PASCAL $7036, $ABFC;
  215.     (*$END*)
  216. (*****************************************************************************************
  217. * 
  218. *  GetScrapDataProcPtr
  219. * 
  220. *  This is a prototype for the function you must supply to TranslateScrap. It is called to 
  221. *  get the data to be translated.  The first call TranslateScrap will make to this is to
  222. *  ask for the LONG("fmts") data.  That is a special.   You should resize and fill in the handle
  223. *  with a list all the formats that you have available to be translated, and the length of each.
  224. *  (See I.M. VI 4-23 for details of LONG("fmts")).  It will then be called again asking for one of  
  225. *  the formats that LONG("fmts") list said was available.
  226. * 
  227. *  Enter:    requestedFormat            Format of data that TranslateScrap needs.
  228. *             dataH                    Types.Handle in which to put the requested data
  229. *             srcDataGetterRefCon        Extra parameter for you passed to TranslateScrap
  230. *             
  231. *  Exit:    dataH                    Types.Handle is resized and filled with data in requested format
  232. *)
  233. TYPE
  234.     GetScrapDataProcPtr* = (*ΔΔ Types.ProcPtr;*) PROCEDURE (requestedFormat: TranslationExtensions.ScrapType; dataH: Types.Handle; srcDataGetterRefCon: (*ΔΔUNIVΔΔ*) Types.Ptr): Types.OSErr;
  235.     GetScrapDataUPP* = Types.UniversalProcPtr;
  236.  
  237. CONST
  238.     uppGetScrapDataProcInfo* = $00000FE0; (* PROCEDURE (4 byte param, 4 byte param, 4 byte param): 2 byte result; *)
  239.  
  240. PROCEDURE NewGetScrapDataProc*(userRoutine: GetScrapDataProcPtr): GetScrapDataUPP;
  241.     (*$IF NOT GENERATINGCFM *)
  242.     INLINE PASCAL $2E9F;
  243.     (*$END*)
  244.  
  245. PROCEDURE CallGetScrapDataProc*(requestedFormat: TranslationExtensions.ScrapType; dataH: Types.Handle; srcDataGetterRefCon: (*ΔΔUNIVΔΔ*) Types.Ptr; userRoutine: GetScrapDataUPP): Types.OSErr;
  246.     (*$IF NOT GENERATINGCFM*)
  247.     INLINE PASCAL $205F, $4E90;
  248.     (*$END*)
  249.     
  250. TYPE
  251.     GetScrapData* = GetScrapDataUPP;
  252.  
  253. (*****************************************************************************************
  254. * 
  255. *  TranslateScrap
  256. * 
  257. *  This routine resizes the destination handle and fills it with data of the requested format.
  258. *  The data is generated by translated one or more source formats of data supplied by
  259. *  the procedure srcDataGetter*.  
  260. *  This routine is automatically called by GetScrap and ReadEdition.  You only need to call
  261. *  this if you need to translated scrap style data, but are not using the ScrapMgr or EditionMgr.
  262. * 
  263. *  Enter:    sourceDataGetter            Pointer to routine that can get src data
  264. *             sourceDataGetterRefCon        Extra parameter for dataGetter
  265. *             destinationFormat            Format of data desired
  266. *             destinationData                Types.Handle in which to store translated data
  267. *             
  268. *  Exit:    dstData                        Types.Handle is resized and filled with data in requested format
  269. *)
  270.  
  271. PROCEDURE TranslateScrap*(sourceDataGetter: GetScrapData; sourceDataGetterRefCon: (*ΔΔUNIVΔΔ*) Types.Ptr; destinationFormat: TranslationExtensions.ScrapType; destinationData: Types.Handle; progressDialogID: INTEGER): Types.OSErr;
  272.     (*$IF NOT GENERATINGCFM*)
  273.     INLINE PASCAL $700E, $ABFC;
  274.     (*$END*)
  275.  
  276. (* $ALIGN RESET*)
  277. (* $POP*)
  278.  
  279.  END Translation.
  280. (*$END*)
  281.